Python kodo kokybė: „Black“, „Flake8“ ir „mypy“ integracijos įvaldymas

Programinės įrangos kūrimo pasaulyje veikiančio kodo parašymas yra tik pusė darbo. Nuoseklaus stiliaus palaikymas, geriausių praktikų laikymasis ir tipų saugumo užtikrinimas yra vienodai svarbūs kuriant patikimus, palaikomus ir bendradarbiavimui pritaikytus projektus. Python, žinomas dėl savo skaitomumo, labai laimi iš įrankių, kurie automatizuoja šiuos aspektus. Šiame išsamiame vadove nagrinėjama trijų galingų įrankių integracija: „Black“, „Flake8“ ir „mypy“, siekiant pakelti jūsų Python kodo kokybę į kitą lygį.

Kodėl kodo kokybė yra svarbi

Prieš gilinantis į kiekvieno įrankio specifiką, supraskime, kodėl kodo kokybė yra svarbiausia:

• Skaitomumas: Nuoseklus kodo stilius palengvina programuotojams suprasti ir keisti kodą.
• Palaikomumas: Gerai suformatuotas ir tipų patikrą praėjęs kodas sumažina klaidų tikimybę ir supaprastina derinimą.
• Bendradarbiavimas: Bendri kodo stiliai užtikrina, kad visi komandos nariai rašytų kodą vienodai, skatindami sklandų bendradarbiavimą.
• Sumažinta techninė skola: Ankstyvas kodo kokybės problemų sprendimas neleidžia kauptis techninei skolai, ilgainiui taupant laiką ir išteklius.
• Padidintas patikimumas: Statinis tipų tikrinimas pagauna galimas klaidas prieš vykdymo laiką, pagerindamas jūsų programų bendrą patikimumą.

Šie privalumai neapsiriboja konkrečiomis pramonės šakomis ar regionais. Nesvarbu, ar kuriate internetinę programą Berlyne, duomenų mokslo projektą Bangalore, ar mobiliąją programėlę Meksike, nuosekli kodo kokybė neabejotinai pagerins jūsų kūrimo procesą.

Pristatome „Black“: bekompromisį kodo formatuotoją

„Black“ yra Python kodo formatuotojas, kuris automatiškai performatuoja jūsų kodą, kad jis atitiktų nuoseklų stilių. Jis yra „nuomonę turintis“ (angl. opinionated), o tai reiškia, kad jis priima sprendimus už jus, kaip kodas turėtų būti formatuojamas, sumažindamas diskusijas dėl stiliaus ir leisdamas programuotojams susitelkti ties funkcionalumu.

Pagrindinės „Black“ savybės

• Automatinis formatavimas: „Black“ automatiškai performatuoja jūsų kodą pagal savo iš anksto nustatytą stiliaus vadovą (remiantis PEP 8).
• Bekompromisis: „Black“ palieka mažai erdvės pritaikymui, užtikrindamas nuoseklų stilių visoje jūsų kodo bazėje.
• Integracija su redaktoriais: „Black“ sklandžiai integruojasi su populiariais kodo redaktoriais, tokiais kaip VS Code, PyCharm ir Sublime Text.
• „Pre-commit“ kablys: „Black“ gali būti naudojamas kaip „pre-commit“ kablys, siekiant užtikrinti, kad visas į jūsų repozitoriją įkeliamas kodas būtų tinkamai suformatuotas.

„Black“ diegimas

Galite įdiegti „Black“ naudodami pip:

            pip install black
            

              
                Copy
              
            
          

„Black“ naudojimas

Norėdami suformatuoti Python failą su „Black“, tiesiog paleiskite šią komandą:

            black my_file.py
            

              
                Copy
              
            
          

„Black“ performatuos failą vietoje, laikydamasis savo iš anksto nustatytų stiliaus taisyklių. Norėdami suformatuoti visą katalogą, paleiskite:

            black my_directory
            

              
                Copy
              
            
          

Pavyzdys: formatavimas su „Black“

Apsvarstykite šį prastai suformatuotą Python kodą:

            def my_function(  long_argument_name, another_long_argument_name):
    if long_argument_name > 10:
        return  another_long_argument_name   +  long_argument_name
    else:
        return 0
            

              
                Copy
              
            
          

Paleidus „Black“, kodas bus automatiškai performatuotas taip:

            def my_function(long_argument_name, another_long_argument_name):
    if long_argument_name > 10:
        return another_long_argument_name + long_argument_name
    else:
        return 0
            

              
                Copy
              
            
          

Atkreipkite dėmesį, kaip „Black“ automatiškai pakoregavo tarpus, eilučių lūžius ir įtraukas, kad atitiktų savo stiliaus vadovą.

„Black“ integravimas su „Pre-commit“

„Pre-commit“ yra įrankis, leidžiantis paleisti patikras jūsų kode prieš jį įkeliant į repozitoriją. „Black“ integravimas su „pre-commit“ užtikrina, kad visas įkeliamas kodas būtų tinkamai suformatuotas.

1. Įdiekite „pre-commit“:

            pip install pre-commit
            

              
                Copy
              
            
          

2. Sukurkite .pre-commit-config.yaml failą savo repozitorijos šakniniame kataloge:

            repos:
-   repo: https://github.com/psf/black
    rev: 23.12.1  # Pakeiskite naujausia versija
    hooks:
    -   id: black
            

              
                Copy
              
            
          

3. Įdiekite „pre-commit“ kablius:

            pre-commit install
            

              
                Copy
              
            
          

Dabar kiekvieną kartą, kai įkelsite kodą, „pre-commit“ paleis „Black“, kad suformatuotų jūsų failus. Jei „Black“ atliks pakeitimus, įkėlimas bus nutrauktas, ir jums reikės paruošti pakeitimus (stage) ir įkelti dar kartą.

Pristatome „Flake8“: kodo stiliaus tikrintuvą

„Flake8“ yra apvalkalas aplink kelis populiarius Python „lintinimo“ įrankius, įskaitant pycodestyle (anksčiau pep8), pyflakes ir mccabe. Jis tikrina jūsų kodą dėl stiliaus klaidų, sintaksės klaidų ir kodo sudėtingumo problemų, padėdamas jums laikytis PEP 8 stiliaus vadovo ir rašyti švaresnį, lengviau palaikomą kodą.

Pagrindinės „Flake8“ savybės

• Stiliaus klaidų aptikimas: „Flake8“ nustato PEP 8 stiliaus vadovo pažeidimus, tokius kaip neteisinga įtrauka, eilutės ilgio pažeidimai ir nenaudojami importai.
• Sintaksės klaidų aptikimas: „Flake8“ aptinka sintaksės klaidas jūsų kode, padėdamas anksti pagauti galimas klaidas.
• Kodo sudėtingumo analizė: „Flake8“ naudoja mccabe, kad apskaičiuotų jūsų kodo ciklomatrinį sudėtingumą, nustatydamas potencialiai sudėtingas ir sunkiai palaikomas funkcijas.
• Išplečiamumas: „Flake8“ palaiko platų įskiepių asortimentą, leidžiantį pritaikyti jo elgseną ir pridėti papildomų patikrų palaikymą.

„Flake8“ diegimas

Galite įdiegti „Flake8“ naudodami pip:

            pip install flake8
            

              
                Copy
              
            
          

„Flake8“ naudojimas

Norėdami patikrinti Python failą su „Flake8“, tiesiog paleiskite šią komandą:

            flake8 my_file.py
            

              
                Copy
              
            
          

„Flake8“ išves sąrašą visų stiliaus klaidų, sintaksės klaidų ar kodo sudėtingumo problemų, kurias ras faile. Norėdami patikrinti visą katalogą, paleiskite:

            flake8 my_directory
            

              
                Copy
              
            
          

Pavyzdys: stiliaus klaidų nustatymas su „Flake8“

Apsvarstykite šį Python kodą:

            def my_function(x,y):
    if x> 10:
        return x+y
    else:
        return 0
            

              
                Copy
              
            
          

Paleidus „Flake8“ šiam kodui, bus gauta ši išvestis:

            my_file.py:1:1: E302 expected 2 blank lines, found 0
my_file.py:1:14: E231 missing whitespace after ','
my_file.py:2:4: E128 continuation line under-indented for visual indent
my_file.py:3:12: E226 missing whitespace around operator

            

              
                Copy
              
            
          

„Flake8“ nustatė kelias stiliaus klaidas, įskaitant trūkstamas tuščias eilutes, trūkstamą tarpą po kablelio, neteisingą įtrauką ir trūkstamą tarpą aplink operatorių. Šias klaidas reikėtų ištaisyti, siekiant pagerinti kodo skaitomumą ir atitiktį PEP 8.

„Flake8“ konfigūravimas

„Flake8“ galima konfigūruoti naudojant .flake8 failą jūsų repozitorijos šakniniame kataloge. Šis failas leidžia nurodyti, kurias patikras įjungti ar išjungti, nustatyti maksimalų eilutės ilgį ir konfigūruoti kitus nustatymus.

Štai .flake8 failo pavyzdys:

            [flake8]
max-line-length = 120
ignore = E203, W503
            

              
                Copy
              
            
          

Šiame pavyzdyje maksimalus eilutės ilgis nustatytas į 120 simbolių, o E203 ir W503 patikros yra išjungtos. E203 reiškia tarpą prieš ':', ir tai dažnai laikoma stilistiniu pasirinkimu, kurį vis tiek tvarko „Black“. W503 reiškia eilutės lūžį prieš dvejetainį operatorių, ką taip pat sprendžia „Black“.

„Flake8“ integravimas su „Pre-commit“

Norėdami integruoti „Flake8“ su „pre-commit“, pridėkite šiuos eilutes į savo .pre-commit-config.yaml failą:

            -   repo: https://github.com/pycqa/flake8
    rev: 6.1.0 # Pakeiskite naujausia versija
    hooks:
    -   id: flake8
            

              
                Copy
              
            
          

Dabar kiekvieną kartą, kai įkelsite kodą, „pre-commit“ paleis „Flake8“, kad patikrintų stiliaus klaidas. Jei „Flake8“ ras klaidų, įkėlimas bus nutrauktas, ir jums reikės ištaisyti klaidas ir įkelti dar kartą.

Pristatome „mypy“: statinį tipų tikrintuvą

„mypy“ yra statinis tipų tikrintuvas Python kalbai, padedantis pagauti tipų klaidas prieš vykdymo laiką. Python yra dinamiškai tipizuojama kalba, o tai reiškia, kad kintamojo tipas nėra tikrinamas iki vykdymo laiko. Tai gali sukelti netikėtų klaidų. „mypy“ leidžia pridėti tipų užuominas (type hints) į jūsų kodą, įgalinant statinį tipų tikrinimą ir gerinant jūsų programų patikimumą.

Pagrindinės „mypy“ savybės

• Statinis tipų tikrinimas: „mypy“ tikrina kintamųjų, funkcijų argumentų ir grąžinamų verčių tipus kompiliavimo metu, pagaudamas galimas tipų klaidas prieš vykdymo laiką.
• Tipų užuominos: „mypy“ naudoja tipų užuominas, kurios yra anotacijos, nurodančios laukiamą kintamojo ar funkcijos tipą.
• Laipsniškas tipavimas: „mypy“ palaiko laipsnišką tipavimą (gradual typing), o tai reiškia, kad galite pridėti tipų užuominas į savo kodą palaipsniui, nereikės iš karto patikrinti visos savo kodo bazės.
• Integracija su redaktoriais: „mypy“ sklandžiai integruojasi su populiariais kodo redaktoriais, tokiais kaip VS Code ir PyCharm.

„mypy“ diegimas

Galite įdiegti „mypy“ naudodami pip:

            pip install mypy
            

              
                Copy
              
            
          

„mypy“ naudojimas

Norėdami patikrinti Python failą su „mypy“, tiesiog paleiskite šią komandą:

            mypy my_file.py
            

              
                Copy
              
            
          

„mypy“ išves sąrašą visų tipų klaidų, kurias ras faile. Norėdami patikrinti visą katalogą, paleiskite:

            mypy my_directory
            

              
                Copy
              
            
          

Pavyzdys: tipų užuominų pridėjimas ir tipų klaidų aptikimas

Apsvarstykite šį Python kodą:

            def add(x, y):
    return x + y

result = add(10, "20")
print(result)
            

              
                Copy
              
            
          

Šis kodas veiks be klaidų, tačiau duos netikėtų rezultatų, nes sudeda sveikąjį skaičių ir eilutę. Norėdami pagauti šią tipo klaidą, galite pridėti tipų užuominas į add funkciją:

            def add(x: int, y: int) -> int:
    return x + y

result = add(10, "20")
print(result)
            

              
                Copy
              
            
          

Dabar, kai paleisite „mypy“, jis išves šią klaidą:

            my_file.py:4: error: Argument 2 to "add" has incompatible type "str"; expected "int"
            

              
                Copy
              
            
          

„mypy“ aptiko, kad perduodate eilutę funkcijai add, kuri tikisi sveikojo skaičiaus. Tai leidžia jums pagauti klaidą prieš vykdymo laiką ir išvengti netikėtos elgsenos.

„mypy“ konfigūravimas

„mypy“ galima konfigūruoti naudojant mypy.ini arba pyproject.toml failą jūsų repozitorijos šakniniame kataloge. Šis failas leidžia nurodyti, kurias patikras įjungti ar išjungti, nustatyti Python versiją ir konfigūruoti kitus nustatymus. Naudoti pyproject.toml yra modernus rekomenduojamas būdas.

Štai pyproject.toml failo pavyzdys:

            [tool.mypy]
python_version = "3.11"
strict = true
            

              
                Copy
              
            
          

Šiame pavyzdyje Python versija nustatyta į 3.11, ir įjungtas griežtas režimas (strict mode). Griežtas režimas įjungia visas griežčiausias „mypy“ patikras, padedant pagauti dar daugiau galimų tipų klaidų.

„mypy“ integravimas su „Pre-commit“

Norėdami integruoti „mypy“ su „pre-commit“, pridėkite šiuos eilutes į savo .pre-commit-config.yaml failą:

            -   repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.6.1 # Pakeiskite naujausia versija
    hooks:
    -   id: mypy
            

              
                Copy
              
            
          

Dabar kiekvieną kartą, kai įkelsite kodą, „pre-commit“ paleis „mypy“, kad patikrintų tipų klaidas. Jei „mypy“ ras klaidų, įkėlimas bus nutrauktas, ir jums reikės ištaisyti klaidas ir įkelti dar kartą.

Visko sujungimas: išsamus integracijos pavyzdys

Norėdami pademonstruoti „Black“, „Flake8“ ir „mypy“ integracijos galią, panagrinėkime išsamų pavyzdį. Apsvarstykite šį Python kodą:

            def calculate_average(numbers):
    sum=0
    for number in numbers:
        sum+=number
    return sum/len(numbers)
            

              
                Copy
              
            
          

Šis kodas turi keletą problemų:

• Jis nėra suformatuotas pagal PEP 8.
• Jame trūksta tipų užuominų.
• Jis naudoja potencialiai klaidinantį kintamojo pavadinimą (sum).
• Jis neapdoroją atvejo, kai įvesties sąrašas yra tuščias (dalyba iš nulio).

Pirmiausia paleiskite „Black“, kad suformatuotumėte kodą:

            black my_file.py
            

              
                Copy
              
            
          

„Black“ performatuos kodą taip:

            def calculate_average(numbers):
    sum = 0
    for number in numbers:
        sum += number
    return sum / len(numbers)
            

              
                Copy
              
            
          

Toliau paleiskite „Flake8“, kad patikrintumėte stiliaus klaidas:

            flake8 my_file.py
            

              
                Copy
              
            
          

„Flake8“ išves šias klaidas:

            my_file.py:2:1: F841 local variable 'sum' is assigned to but never used
my_file.py:4:11: F821 undefined name 'numbers'

            

              
                Copy
              
            
          

Ištaisius „Flake8“ klaidas (atkreipkite dėmesį, kad ši konkreti klaidų išvestis gali skirtis priklausomai nuo jūsų „flake8“ konfigūracijos) ir pridėjus tipų užuominas, kodas tampa toks:

            from typing import List

def calculate_average(numbers: List[float]) -> float:
    """Calculates the average of a list of numbers."""
    if not numbers:
        return 0.0  # Avoid division by zero
    total = sum(numbers)
    return total / len(numbers)
            

              
                Copy
              
            
          

Galiausiai paleiskite „mypy“, kad patikrintumėte tipų klaidas:

            mypy my_file.py
            

              
                Copy
              
            
          

Jei tipų klaidų nėra, „mypy“ nieko neišves. Šiuo atveju patikra sėkminga. Dabar kodas suformatuotas pagal PEP 8, turi tipų užuominas, naudoja aprašomuosius kintamųjų pavadinimus ir tvarkosi su atveju, kai įvesties sąrašas yra tuščias. Tai parodo, kaip „Black“, „Flake8“ ir „mypy“ gali dirbti kartu, siekiant pagerinti jūsų Python kodo kokybę ir patikimumą.

Praktinės įžvalgos ir gerosios praktikos

• Pradėkite anksti: Integruokite „Black“, „Flake8“ ir „mypy“ į savo kūrimo procesą nuo pat projektų pradžios. Tai padės jums išlaikyti nuoseklų kodo stilių ir anksti pagauti galimas klaidas.
• Konfigūruokite savo įrankius: Pritaikykite „Black“, „Flake8“ ir „mypy“ savo specifiniams poreikiams ir pageidavimams. Naudokite konfigūracijos failus, kad nurodytumėte, kurias patikras įjungti ar išjungti, nustatytumėte maksimalų eilutės ilgį ir konfigūruotumėte kitus nustatymus.
• Naudokite „Pre-commit“ kablius: Integruokite „Black“, „Flake8“ ir „mypy“ su „pre-commit“, siekdami užtikrinti, kad visas į jūsų repozitoriją įkeliamas kodas būtų tinkamai suformatuotas ir patikrintas pagal tipus.
• Automatizuokite savo darbo eigą: Naudokite CI/CD vamzdynus (pipelines), kad automatiškai paleistumėte „Black“, „Flake8“ ir „mypy“ kiekvienam įkėlimui. Tai padės jums pagauti kodo kokybės problemas, kol jos dar nepateko į produkciją. Tokios paslaugos kaip GitHub Actions, GitLab CI ir Jenkins gali būti sukonfigūruotos automatiškai paleisti šias patikras.
• Švieskite savo komandą: Užtikrinkite, kad visi komandos nariai būtų susipažinę su „Black“, „Flake8“ ir „mypy“ ir suprastų, kaip juos efektyviai naudoti. Suteikite mokymus ir dokumentaciją, kad padėtumėte savo komandai įsisavinti šiuos įrankius ir palaikyti nuoseklų kodo stilių.
• Taikykite laipsnišką tipavimą: Jei dirbate su didele, esama kodo baze, apsvarstykite galimybę taikyti laipsnišką tipavimą. Pradėkite nuo tipų užuominų pridėjimo prie svarbiausių kodo dalių ir palaipsniui didinkite aprėptį.

Išvada

Investavimas į kodo kokybę yra investicija į ilgalaikę jūsų projektų sėkmę. Integruodami „Black“, „Flake8“ ir „mypy“ į savo kūrimo procesą, galite žymiai pagerinti savo Python kodo skaitomumą, palaikomumą ir patikimumą. Šie įrankiai yra būtini bet kuriam rimtam Python programuotojui, nepriklausomai nuo jo vietos ar projektų pobūdžio. Nuo startuolių Silicio slėnyje iki įsitvirtinusių įmonių Singapūre, šių gerųjų praktikų taikymas neabejotinai lems efektyvesnį ir veiksmingesnį programinės įrangos kūrimą.

Nepamirškite pritaikyti šių gairių ir įrankių savo konkrečiam kontekstui. Eksperimentuokite su skirtingomis konfigūracijomis, tyrinėkite galimus įskiepius ir pritaikykite savo darbo eigą, kad atitiktų unikalius jūsų komandos ir projektų poreikius. Nuolat siekdami aukštesnės kodo kokybės, būsite gerai pasirengę kurti patikimas, keičiamo dydžio ir palaikomas programas, kurios teiks vertę jūsų vartotojams daugelį metų.